#ifndef OMG_DDS_ENTITY_HPP_ 
#define OMG_DDS_ENTITY_HPP_

/* Copyright (c) 2009-2010, Real-Time Innovations, Inc.
 * Copyright (c) 2010, Object Management Group, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 * - Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - Neither the names of the above copyright holders nor the names of their
 *   contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL A COPYRIGHT HOLDER OR CONTRIBUTOR BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */


/**
 * This class is the abstract base class for all the DCPS objects that 
 * support QoS policies, a listener and a status condition. In the 
 * ISO C++ PSM each DDS entity behaves like a polymorphic reference 
 * in what it automatically manages its resource and it can be 
 * safely assigned up and down the DDS Entity type hierarchy.
 */
template <typename DELEGATE>
class tdds::core::Entity : public dds::core::Reference<DELEGATE>
{
    OMG_DDS_REFERENCE_TYPE(Entity)

public:
    /**
     * This operation enables the Entity. Entity objects can be created
     * either enabled or disabled. This is controlled by the value of 
     * the ENTITY_FACTORY Qos policy (Section 7.1.3.20, “ENTITY_FACTORY) 
     * on the corresponding factory for the Entity.
     * The default setting of ENTITY_FACTORY is such that, by default, 
     * it is not necessary to explicitly call enable on newly created 
     * entities (see Section 7.1.3.20, “ENTITY_FACTORY).
     * The enable operation is idempotent. Calling enable on an already 
     * enabled Entity does nor raise exceptions and has no effect.
     *
     * Entities created from a factory that is disabled, are created 
     * disabled regardless of the setting of the ENTITY_FACTORY
     * Qos policy. Calling enable on an Entity whose factory is not 
     * enabled will fail and return PRECONDITION_NOT_MET.
     * If the ENTITY_FACTORY Qos policy has autoenable_created_entities
     * set to TRUE, the enable operation on the factory will automatically 
     * enable all entities created from the factory.
     * The Listeners associated with an entity are not called until 
     * the entity is enabled. Conditions associated with an entity that 
     * is not enabled are “inactive,” that is, have a trigger_value==FALSE 
     * (see Section 7.1.4.4, “Conditions and Wait-sets,” on page 131).
     */
    virtual void enable();

    virtual void set_qos(const std::string& qos_library_name,
                         const std::string& qos_profile_name);

    /**
     * This operation retrieves the list of communication statuses in the
     * Entity that are "triggered." That is, the list of statuses whose value
     * has changed since the last time the application read the status. 
     * The precise definition of the ‘triggered’ state of communication
     * statuses is given in Section 7.1.4.2, “Changes in Status,” on page 126.
     * When the entity is first created or if the entity is not enabled, 
     * all communication statuses are in the “untriggered” state so the list 
     * returned by the get_status_changes operation will be empty.
     * The list of statuses returned by the get_status_changes operation
     * refers to the statuses that are triggered on the Entity itself and
     * does not include statuses that apply to contained entities.
     *
     * @return the status changes
     */
    virtual const dds::core::StatusMask get_status_changes();

    /**
     * This operation returns the InstanceHandle_t that 
     * represents the Entity.
     */
    virtual const dds::core::InstanceHandle get_instancehandle();

    virtual void close();

    /**
     * Indicates that references to this object may go out of scope but that
     * the application expects to look it up again later. Therefore, the
     * Service must consider this object to be still in use and may not
     * close it automatically.
     */
    virtual void retain();
};


#endif // !defined(OMG_DDS_ENTITY_HPP_)
